% BEGIN LICENSE BLOCK
% Version: CMPL 1.1
%
% The contents of this file are subject to the Cisco-style Mozilla Public
% License Version 1.1 (the "License"); you may not use this file except
% in compliance with the License.  You may obtain a copy of the License
% at www.eclipse-clp.org/license.
% 
% Software distributed under the License is distributed on an "AS IS"
% basis, WITHOUT WARRANTY OF ANY KIND, either express or implied.  See
% the License for the specific language governing rights and limitations
% under the License. 
% 
% The Original Code is  The ECLiPSe Constraint Logic Programming System. 
% The Initial Developer of the Original Code is  Cisco Systems, Inc. 
% Portions created by the Initial Developer are
% Copyright (C) 2006 Cisco Systems, Inc.  All Rights Reserved.
% 
% Contributor(s): 
% 
% END LICENSE BLOCK

\chapter{Style Guide}
%HEVEA\cutdef[1]{section}
\label{styleguide}

Every {\eclipse} programming project should adopt a number of style rules.
This appendix gives only a sample set of rules, which can serve as a guideline.
Project teams should adapt them to their own needs and taste.

\section{Style rules}
\begin{enumerate}
\item  There is one directory containing all code and its documentation (using sub-directories).
\item  Filenames\index{file name} are of form [a-z][a-z\_]+ with extension .ecl .
\item  One file per module, one module per file.
\item  Each module is documented with comment directives.
\item  All required interfaces are defined in separate spec files which are included in the source with a {\it comment include} directive. This helps to separate specification and implementation code.
\item  The actual data of the problem is loaded dynamically from the Java interface; for stand-alone testing data files from the data directory are included in the correct modules.
\item  The file name is equal to the module name.
\item  Predicate names\index{predicate name} are of form [a-z][a-z\_]*[0-9]* . Underscores are used to separate words. Digits should only be used at the end of the name. Words should be English.
\item  Variable names\index{variable name} are of form [A-Z\_][a-zA-Z]*[0-9]* . Separate words with capital letters. Digits should only be used at the end. Words should be English.
\item  The code should not contain singleton variables\index{singleton}, unless their names start with \_. The final program may not generate singleton warnings.
\item  Each exported predicate is documented with a comment directive\index{comment directive}.
\item  Clauses for a predicate must be consecutive.
\item  Base clauses should be stated before recursive cases.
\item  Input arguments should be placed before output arguments.
\item  Predicates which are not exported should be documented with a single line comment. It is possible to use comment directives instead.
\item  The sequence of predicates in a file is top-down with a (possibly empty) utility section at the end.
\item  All structures are defined in one file (e.g. flow\_structures.ecl) and are documented with comment directives.
\item  Terms should not be used; instead use named structures\index{named structure}.
\item  When possible, use do-loops instead of recursion.
\item  When possible, use separate predicates instead of disjunction\index{disjunction} or if-then-else.
\item  There should be no nested if-then-else\index{if then else} construct in the code.
\item  All input data should be converted into structures at the beginning of the program; there should be no direct access to the data afterwards. 
\item  All integer constants\index{integer constants} should be parametrized via facts. There should be no integer values (others than 0 and 1) in rules.
\item  The final code should not use failure-loops\index{failure loop}; they are acceptable for debugging or testing purposes.
\item  Cuts (!) \index{cut} should be inserted only to eliminate clearly defined choice points.
\item  The final code may not contain open choice points, except for alternative solutions that still can be explored. This is verified with the tracer tool in the debugger.
\item  Customizable data facts should always be at the end of a file; their use is deprecated.
\item  The predicate member/2\index{member/2} should only be used where backtracking is required; otherwise use memberchk/2\index{memberchk/2} to avoid hidden choice points.
\item  The final code may not contain dead code\index{dead code} except in the file/module unsupported.ecl. This file should contain all program pieces which are kept for information/debugging, but which are not part of the deliverable.
\item  The test set(s) should exercise 100 percent of the final code. Conformity is checked with the line coverage profiler.
\item  Explicit unification (=/2) should be replaced with unification inside terms where possible.
\item  There is a top-level file (top.ecl) which can be used to generated all on-line documentation automatically.
\item  For each module, a module diagram is provided.
\item  For the top-level files, component diagrams are provided.
\item  Don't use ','/2 to make tuples.
\item  Don't use lists to make tuples.
\item  Avoid append/3 where possible, use accumulators instead.
\end{enumerate}

\section{Module structure}
The general form of a module is:

\begin{enumerate}
\item  module definition
\item  module comment or inclusion of a spec file
\item  exported/reexported predicates
\item  used modules
\item  used libraries
\item  local variable definitions 
\item  other global operations and settings
\item  predicate definitions
\end{enumerate}

\section{Predicate definition}
The general form of a predicate definition is:

\begin{enumerate}
\item  predicate comment directive
\item  mode declaration
\item  predicate body
\end{enumerate}

%HEVEA\cutend
